home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / uw_1.exe / UW_HELP4.HLP < prev    next >
Text File  |  1992-11-03  |  27KB  |  636 lines
  1. `co(4,7);─────────────────────── /// Rectangle Functions ──────────────────────────────`co();
  2.  
  3.  ┌──────────────────────────────────────────────────────────────────────────┐    
  4.  │       `keyword(set_rect,/// set_rect);               `keyword(is_rect_equal,/// is_rect_equal);           `keyword(rect_overlap,/// rect_overlap);        │
  5.  │       `keyword(offset_rect,/// offset_rect);            `keyword(col_row_inrect,/// col_row_inrect);                              │
  6.  └──────────────────────────────────────────────────────────────────────────┘
  7.  
  8.         The UltraWin library uses the structure RECT to handle information
  9.     dealing with rectangular sections of the screen, as in the WINDOW
  10.     structure.    Included are functions to define the rectangle, check to see
  11.     if one rectangle overlaps another, and several other routines that you may
  12.     wish to utilize in your program.
  13.  
  14. `co(10,1);/// set_rect`co();   `keyword(source,[UW_WIN.C]~set_rect);
  15.         Takes the variable of type RECT passed by pointer, and sets the upper
  16.     left corner and lower right corner to the coordinates passed as integers.
  17.  
  18. Prototype:
  19.     void set_rect(RECT *rectp, int x1, int y1, int x2, int y2);
  20.  
  21. Parameters:
  22. `co(11,1);    RECT *rectp;`co();
  23.         A pointer to the rectangle variable.
  24. `co(11,1);    int x1, y1, x2, y2`co();
  25.         The coordinate pair for the upper left corner (x1,y1) and the lower
  26.         right corner (x2,y2) of the rectangle.
  27.  
  28. Usage:
  29.     RECT r;
  30.     ...
  31.     set_rect( &r, 10, 10, 20, 20 );
  32.  
  33. `co(10,1);/// is_rect_equal`co();   `keyword(source,[UW_WIN.C]~is_rect_equal);
  34.         Checks to see if the two rectangles are the same.
  35.  
  36. Prototype:
  37.     int is_rect_equal(RECT *r1, RECT *r2);
  38.  
  39. Parameters:
  40. `co(11,1);    RECT *r1, *r2;`co();
  41.         Pointers to the two rectangles to compare.
  42.  
  43. Usage:
  44.     RECT r1, r2;
  45.     ...
  46.     if (is_rect_equal( &r1, &r2 )) {}
  47.  
  48. `co(10,1);/// rect_overlap`co();   `keyword(source,[UW_WIN.C]~rect_overlap);
  49.         Reports on the relationship between two rectangles.  This function will
  50.     return the status as one of the following (defined in UW.H):
  51.  
  52.         1) FIRST_ENCLOSED
  53.                  The first rectangle is enclosed within the second.
  54.         2) SECOND_ENCLOSED
  55.                  The second rectangle is enclosed within the first.
  56.         3) OVERLAP
  57.                  The rectangles overlap.
  58.         4) NO_OVERLAP
  59.                  The rectangles do not overlap.
  60.  
  61. Prototype:
  62.     int rect_overlap(RECT *r1, RECT *r2);
  63.  
  64. Parameters:
  65. `co(11,1);    RECT *r1, *r2;`co();
  66.         The two rectangles whose relationship to find.
  67.  
  68. Usage:
  69.     RECT r1, r2;
  70.     int status;
  71.     ...
  72.     status = rect_overlap( &r1, &r2 );
  73.  
  74. `co(10,1);/// offset_rect`co();   `keyword(source,[UW_WIN.C]~offset_rect);
  75.         Moves the rectangles coordinates by a fixed positive or negative amount
  76.     in both the x (column) and y (row) direction.
  77.  
  78. Prototype:
  79.     void offset_rect(RECT *rectp, int col, int row);
  80.  
  81. Parameters:
  82. `co(11,1);    RECT *rectp;`co();
  83.         A pointer to the rectangle variable.
  84. `co(11,1);    int col, row`co();
  85.         The offsets to add to the rectangle's coordinates.
  86.  
  87. Usage:
  88.     RECT r;
  89.     ...
  90.     offset_rect( &r, 5, -4 );
  91.  
  92. `co(10,1);/// col_row_inrect`co();   `keyword(source,[UW_WIN.C]~cr_inrect);
  93.         Checks to see if a particular location is inside (or on the border of)
  94.     the rectangle passed.
  95.  
  96. Prototype:
  97.     int col_row_inrect(int col, int row, RECT *rectp);
  98.  
  99. Parameters:
  100. `co(11,1);    int col, row`co();
  101.         The coordinate to check.
  102. `co(11,1);    RECT *rectp;`co();
  103.         A pointer to the rectangle.
  104.  
  105. Usage:
  106.     RECT r;
  107.     ...
  108.     if (col_row_inrect( 5, 5, &r )) {}
  109.  
  110. `co(4,7);──────────────────────────── /// Data Entry ──────────────────────────────────`co();
  111.  
  112.  ┌──────────────────────────────────────────────────────────────────────────┐    
  113.  │           `keyword(wn_gets,/// wn_gets);                            `keyword(Masks/Templates,/// Masks/Templates);             │
  114.  │           `keyword(Validation Chars,/// Validation Chars);                   `keyword(Strip Mask Option,/// Strip Mask Option);           │
  115.  │           `keyword(wn_gets_ll,/// wn_gets_ll);                                                                     │
  116.  └──────────────────────────────────────────────────────────────────────────┘
  117.  
  118.       One of the most flexible of all functions in the UltraWin library is
  119.     wn_gets.  With this one function you can have the user enter dates, times,
  120.     prices, strings, and any other type with full control over every character
  121.     entered!  UltraWin versions 2.00 and up add an even more powerful lower
  122.     level function now called by wn_gets to enhance the capabilities even
  123.     further.  Full compatibility is maintained.  The new function called
  124.     wn_gets_ll has added the capability to uppercase the first character of
  125.     each word, strip the mask completely, only strip the end, or not strip at
  126.     all.  It can also get input right-to-left, clear an input on the first
  127.     non-keypad keypress, and exit when the last character in the input is
  128.     entered, saving an extra <Enter> keypress.  Furthermore it can allow the
  129.     user to input a string longer than the display width of the field and will
  130.     scroll within this region automatically!  It can also display arrows to
  131.     show the user that the string has data to the left or right of the current
  132.     display field.  If this isn't enough for you, we've added the ability to
  133.     call your own validation function for every character entered in
  134.     wn_gets_ll.  This allows you to validate the user's input "as it happens",
  135.     and enhance wn_gets_ll. A new wn_gets_ll hook added in version 2.10 allows
  136.     both pre and post processing, as well as the ability to modify the event
  137.     itself, giving you the ability to translate keys.
  138.     
  139.     See also `keyword(set_validation_func,/// set_validation_func);.
  140.  
  141. `co(10,1);/// wn_gets`co();   `keyword(source,[UW_ENTRY.C]~wn_gets);
  142.         Gets input from the user according to the restrictions of the mask and
  143.     template strings in the window passed by pointer.  This function will pass
  144.     back the input either with the mask characters included in the string, or
  145.     stripped out.    A -1 is returned if the mouse is clicked off of the string,
  146.     and one of the values KEY_UP, KEY_DN, KEY_PGUP, KEY_PGDN, KEY_ESC,
  147.     KEY_ENTER, KEY_TAB or KEY_SHFT_TAB (defined in UW_KEYS.H) is returned if
  148.     pressed.  Read about the mask and template strings for more information.
  149.  
  150. Prototype:
  151.     int wn_gets( char *str, char *mask, char *template, uchar m_att,
  152.                              int strip_mode, WINDOW *wnp );
  153.  
  154. Parameters:
  155. `co(11,1);    char *str`co();
  156.         The string to be returned by the function.
  157. `co(11,1);    char *mask`co();
  158.         The mask string.
  159. `co(11,1);    char *template`co();
  160.         The template string.
  161. `co(11,1);    uchar m_att`co();
  162.         The attribute (colors) to use when displaying the string.
  163. `co(11,1);    int strip_mode`co();
  164.         Set to 1 (STRIP_ON) to strip mask characters out of result, or set to 0
  165.         (STRIP_OFF) for full mask and result.
  166. `co(11,1);    WINDOW *wnp;`co();
  167.         A pointer to the window in which entry is to take place.
  168.  
  169. Usage:
  170.     WINDOW *wnp;
  171.     int result;
  172.     char s[80];
  173.     ...
  174.     result = wn_gets( s, "(___)-___-____", "###  ### ####",
  175.                                         wnp->att, STRIP_ON, wnp);
  176.  
  177. `co(10,1);/// Masks/Templates`co();
  178.  
  179.     The wn_gets function requires you to specify two important strings to
  180.     perform its magic.  These are the mask and template strings.
  181.  
  182.     The mask string gives you the flexibility of displaying textual
  183.     information inside the area to be typed by the user.    The mask characters
  184.     are displayed in each position of the string that does not have text.
  185.  
  186.     The template string is essentially a string containing validation
  187.     characters.  Before a character is entered into the string, the wn_gets
  188.     function compares the typed character with the template to see if the
  189.     character is valid.  In addition, the template can be used to force an
  190.     uppercase or lowercase character without having the user touch the
  191.     CapsLock or Shift keys.
  192.  
  193.     When combined, the mask and template strings give you great flexibility.
  194.     The following are just a few examples with explanations of what they
  195.     accomplish:
  196.  
  197.     mask = "________"           Enter an 8 character string, where all
  198.     tplt = "AAAAAAAA"           characters must be alphanumeric.
  199.     
  200.     mask = "________"           Enter an 8 character string, where
  201.     tplt = "****